
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" >
<head>
	<title>PlotKit.Layout | liquidx</title>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<link href="http://media.liquidx.net/css/page.css" media="screen" rel="Stylesheet" type="text/css" />
	<link href="http://media.liquidx.net/css/x.css" media="screen" rel="Stylesheet" type="text/css" />
	<link rel="icon" href="/favicon.png" type="image/x-png">
	<link rel="shortcut icon" href="/favicon.png" type="image/x-png">
	<!--[if lt IE 7.]>	
	<script defer type="text/javascript" src="http://media.liquidx.net/js/pngfix.js"></script>
	<![endif]-->
	
<link href="doc.css" media="screen" rel="stylesheet" type="text/css" />

</head>

<body>
    <div id="header">
        <div id="logo"><a href="http://www.liquidx.net/"><img src="http://media.liquidx.net/imgx/logo.png" width="256" height="128" alt="liquidx.net" /></a></div>
		<div id="menu-hack">
			<div id="menu-l"><img src="http://media.liquidx.net/imgx/menu_l.png" width="17" height="28" alt="menu cap" /></div><div id="menu-r"><img src="http://media.liquidx.net/imgx/menu_r.png" width="17" height="28" alt="menu cap" /></div>			
            <div id="menu-main">
        		<ul id="menu" class="code">
            		<li class="tab" id="blog"><a href="http://www.liquidx.net/" title="blog/home">blog</a></li>
            		<li class="tab" id="code"><a href="http://www.liquidx.net/code/" title="software i have written">software</a></li>
            		<li class="tab" id="dev"><a href="http://projects.liquidx.net/" title="source code for my open source projects">dev</a></li>
            		<li class="tab" id="photos"><a href="http://al.tse.id.au/gallery/" title="photos and videos">photos</a></li>
             		<li class="tab" id="research"><a href="http://al.tse.id.au/research/" title="research profile">research</a></li>
             		<li class="tab" id="links"><a href="http://www.liquidx.net/links/" title="my bookmarks">linkblog</a></li>
             		<li class="tab" id="stats"><a href="http://stats.liquidx.net/" title="stats for various parts of my website">stats</a></li>
             		<li class="tab" id="status"><a href="http://www.liquidx.net/status/" title="weather report for alastair">status</a></li>
             		<li class="tab" id="about"><a href="http://al.tse.id.au/" title="about alastair tse">aboutme</a></li>
        		</ul>
        	</div>
    	</div>
		<div id="quick">
			<span class="quickbutton"><a href="http://www.liquidx.net/albumartwidget/"><img src="http://media.liquidx.net/imgx/quick_widget.png" alt="album art widget" /></a></span>
			<span class="quickbutton"><a href="http://www.liquidx.net/plotkit/"><img src="http://media.liquidx.net/imgx/quick_plotkit.png" alt="plotkit" /></a></span>
			<span class="quickbutton"><a href="http://www.liquidx.net/fruity/"><img src="http://media.liquidx.net/imgx/quick_fruity.png" alt="fruity" /></a></span>
		</div>
		
	</div>
    
    <div id="body">
<div class="page doc api">

<p> <a href="PlotKit.html">PlotKit Home</a> | <a href="PlotKit.Base.html">&lt;&lt;</a> | <a href="PlotKit.Renderer.html">&gt;&gt;</a> 
</p>

<h1> PlotKit Layout</h1>
<p>PlotKit Layout is the core of the plotting engine. It deals exclusively with laying objects out on a virtual canvas that has the dimension of 1.0 x 1.0.
</p>
<p>The layout engine abstracts away all the complex layout problems with plotting charts and presents a list of objects that need to rendered rather than mixing this with the rendering logic.
</p>
<p>PlotKit Layout also is responsible for simple chart state querying so renderers can implement basic event support for objects on the canvas.
</p>

<h1> Constructor</h1>
<p>  <code>new Layout(style, options);</code> 
</p>
<p>Layout takes the following arguments:
</p>
<p> <strong>style</strong> which can be <code>bar</code>, <code>line</code> or <code>pie</code> which represnts the style of the graph that is desired.
</p>
<p> <strong>options</strong> is a dictionary/associative array of layout options. Unrecognised keys are ignored. The following options are supported:
</p>

<h1> Layout Options</h1>

<h2> Bar and Line Chart layout options</h2>
<table cellpadding="0" cellspacing="0">
  <thead>
    <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>barWidthFillFraction</th>
        <td>Amount of space the total amount of bars should consume per X value.</td>
        <td>Real number</td>
        <td>0.75</td>
    </tr>
    <tr>
        <th>barOrientation</th>
        <td>Orientation of a bar chart. <b>(PlotKit 0.9+ only)</b></td>
        <td>String ("vertical", "horizontal")</td>
        <td>vertical</td>
    </tr>
    
    <tr>
        <th>xAxis</th>
        <td>Minimum and Maximum values on the X axis.</td>
        <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td>
        <td>null</td>
    </tr>
    <tr>
        <th>xNumberOfTicks</th>
        <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td>
        <td>integer</td>
        <td>10</td>
    </tr>
    <tr>
        <th>xOriginIsZero</th>
        <td>Should graph have X axis origin at 0</td>
        <td>boolean</td>
        <td>true</td>
    </tr>
    <tr>
        <th>xTickPrecision</th>
        <td>The number of decimal places we should round to for tick values.</td>
        <td>integer</td>
        <td>1</td>
    </tr>
    <tr>
        <th>xTicks</th>
        <td>X values at which ticks should be drawn. Automatically calculated if not defined using the parameters `xNumberOfTicks` and ``xTickPrecision``.</td>
        <td>Array of {label: "somelabel", v:value}.</td>
        <td>null</td>
    </tr>
    
    <tr>
        <th>yAxis</th>
        <td>Minimum and Maximum values on the Y axis.</td>
        <td>Array of 2 Real numbers. (eg. [0.0, 10.0])</td>
        <td>null</td>
    </tr>
    <tr>
        <th>yNumberOfTicks</th>
        <td>Used when automatically calculating axis ticks. This denotes the number of ticks there should be in the graph.</td>
        <td>integer</td>
        <td>5</td>
    </tr>
    <tr>
        <th>yOriginIsZero</th>
        <td>Should graph have Y axis origin at 0</td>
        <td>true</td>
    </tr>
    <tr>
        <th>yTickPrecision</th>
        <td>The number of decimal places we should round to for tick values.</td>
        <td>integer</td>
        <td>3</td>
    </tr>
    <tr>
        <th>yTicks</th>
        <td>Y values at which ticks should be drawn. Automatically calculated if not defined using the parameters ``yNumberOfTicks`` and ``yTickPrecision``.</td>
        <td>Array of {label: "somelabel", v:value}.</td>
        <td>null</td>
    </tr>
    </tbody>
</table>


<h2> Pie Chart Layout Options</h2>
<table>
  <thead>
    <tr><td>Option name</td><td>Description</td><td>Type</td><td>Default</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>pieRadius</th>
        <td>Radius of the circle to be drawn.</td>
        <td>Real number</td>
        <td>0.4</td>
    </tr>
  </tbody>
</table>


<h1> Layout Properties</h1>
<p>There are some properties you can access, either because you are using a layout inside a renderer or if you would like additional information. Under normal operations, you will not need to, or should modify these parameters.
</p>
<table cellpadding="0" cellspacing="0">
  <thead>
    <tr><td>Property</td><td>Type</td><td>Description</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>style</th>
        <td>String</td>
        <td>This denotes the type of chart this layout is using. Valid values are ``bar``, ``line`` or ``pie``. Renderers will use this to determine which parameter (``bars``, ``points`` or ``slices``) to access in order to get draw the chart.</td>
    </tr>
    <tr>
        <th>bars</th>
        <td>Array of Bar.</td>
        <td>This is a list of rectangles with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``bar``. This array is sorted by dataset and then x-values.</td>
    </tr>
    <tr>
        <th>points</th>
        <td>Array of Point.</td>
        <td>This is a list of points with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``line``. This array is sorted by dataset and then x-values.</td>
    </tr>
    <tr>
        <th>slices</th>
        <td>Array of Slice.</td>
        <td>This is a list of pie slices with values that the renderer should plot. This will only be valid after ``evaluate()`` has run. The properties of ``bar`` is described here. This is only valid if style is ``pie``.</td>
    </tr>
    <tr>
        <th>xticks</th>
        <td>Array of Tick.</td>
        <td>For style in ``bar`` or ``line``, these are the ticks on the X axis. A ``tick`` is represented as a two element array with the first element representing the x position of the tick and the second element representing the string value of the label at that position.</td>
    </tr>
    <tr>
        <th>yticks</th>
        <td>Array of Tick.</td>
        <td>For style in ``bar`` or ``line``, these are the ticks on the Y axis. A ``tick`` is represented as a two element array with the first element representing the y position of the tick and the second element representing the string value of the label at that position.</td>
    </tr>
    <tr>
        <th>datasets</th>
        <td>Associative Array of datasets</td>
        <td>This should normally only be used to find the number of datasets by performing ``keys(layout.datasets)``. If you are looking at this in a renderer, then the layout engine needs to be extended.</td>
    </tr>
  </tbody>
</table>


<h1> Layout Types</h1>
<p>Here are the definition of the types that you will encounter if you access the properties of the Layout object, specifically <code>bars</code>, <code>points</code> and <code>slices</code>. If you are not writing a renderer, you do not need to know this.
</p>

<h2> Bar Type</h2>
<p>Represents a bar that the renderer will draw. It contains the following properties.
</p>
<table cellpadding="0" cellspacing="0">
  <thead>
    <tr><td>Property</td><td>Type</td><td>Description</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>x, y</th>
        <td>float</td>
        <td>top left position of the bar between 0.0 and 1.0.</td>
    </tr>
    <tr>
        <th>w, h</th>
        <td>float</td>
        <td>width and height of the bar from (``x``, ``y``) between 0.0 and 1.0.</td>
    </tr>
    <tr>
        <th>xval, yval</th>
        <td>float</td>
        <td>The actual x value and y value this bar represents.</td>
    </tr>
    <tr>
        <th>name</th>
        <td>string</td>
        <td>Name of the dataset which this bar belongs to.</td>
    </tr>
  </tbody>
</table>


<h2> Point Type</h2>
<p>This represents a point on a line chart.
</p>
<table cellpadding="0" cellspacing="0">
  <thead>
    <tr><td>Property</td><td>Type</td><td>Description</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>x, y</th>
        <td>float</td>
        <td>top left position of the point between 0.0 and 1.0.</td>
    </tr>
    <tr>
        <th>xval, yval</th>
        <td>float</td>
        <td>The actual x value and y value this bar represents.</td>
    </tr>
    <tr>
        <th>name</th>
        <td>string</td>
        <td>Name of the dataset which this bar belongs to.</td>
    </tr>
  </tbody>
</table>


<h2> Slice Type</h2>
<p>This represents a pie slice in a pie chart.
</p>
<table>
  <thead>
    <tr><td>Property</td><td>Type</td><td>Description</td></tr>
  </thead>
 <tbody>
    <tr>
        <th>fraction</th>
        <td>float</td>
        <td>The fractional value this slice represents. This number is between 0.0 and 1.0</td>
    </tr>
    <tr>
        <th>xval, yval</th>
        <td>float</td>
        <td>The x and y values of this slice.</td>
    </tr>
    <tr>
        <th>startAngle</th>
        <td>float</td>
        <td>This is the angle of the start of the slice, in radians.</td>
    </tr>
    <tr>
        <th>endAngle</th>
        <td>float</td>
        <td>This is the angle of the end of the slice, in radians.</td>
    </tr>
  </tbody>
</table>


<h1> Layout Methods</h1>
<ul>
 <li>
      <code>addDataset(name, values)</code> 
 </li>
</ul>
<p>  Adds a dataset to the layout engine and assigns it with <code>name</code>. <code>values</code> is an array of <code>\[x, y\]</code> values.
</p>
<ul>
 <li>
      <code>removeDataset(name)</code> 
 </li>
</ul>
<p> Removes a dataset from the layout engine. In order for the new data to take effect, you must run <code>evaluate()</code>.
</p>
<ul>
 <li>
      <code>addDatasetFromTable(name, tableElement, xcol = 0, ycol = 1)</code> 
 </li>
</ul>
<p>  Handy function to read values off a table. <code>name</code> is the name to give to the dataset just like in <code>addDataset()</code>, <code>tableElement</code> is the table which contains the values. Optionally, the user may specify to extract alternative columns using <code>xcol</code> and <code>ycol</code>. 
</p>
<ul>
 <li>
      <code>evaluate()</code> 
 </li>
</ul>
<p>  Performs the evaluation of the layout. It is not done automatically, and you <strong>must</strong> execute this before passing the layout to a renderer.
</p>
<ul>
 <li>
     hitTest(x, y)
 </li>
</ul>
<p>  Used by renderers to see if a virtual canvas position corresponds to any data. The return value varies per style. For <code>bar</code> charts, it will return the Bar type if it is a hit, or null if not. For <code>line</code>  charts, it will return a value if the point is underneath the highest curve, otherwise null <strong>(TODO: expand this or change implementation)</strong>. For <code>pie</code> charts, it will return the Slice object that is at the point, otherwise null.
</p>
<p>  <strong>Note that the specification of this function is subject to change</strong>.
</p>

<h1> Layout Notes</h1>

<h2> Pie Chart Data and Ticks Restrictions</h2>
<p>Note that you can only use one dataset for pie charts. Only the y value of the dataset will be used, but the x value must be unique and set as it will correspond to the xTicks that are given.
</p>
<p>Labels for pie charts will only use xTicks.
</p>

<h1> Layout Examples</h1>


</div>
</div>
	
	
    
    <div id="footer">
		<div class="block">
			<h3>Syndication Feeds:</h3>
			<p>
				<ul class="tiny">
					<li><a href="http://www.liquidx.net/blog/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Atom Feed for the Blog Entries</a></li>
					<li><a href="http://www.liquidx.net/blog/feed/rss/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />RSS Feed for the Blog Entries</a></li>
					<li><a href="http://www.liquidx.net/comments/feed/atom/" class="feed" title="feed for all posts on liquidx.net"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for All Comments</a></li>
					<li><a href="http://www.liquidx.net/links/feed/atom/" class="feed" title="feed for all bookmarked links"><img src="http://media.liquidx.net/imgx/feed.gif" class="feed" alt="feed" />Feed for Links</a></li>
				</ul>
			</p>
		</div>
		<div class="block">
			<h3>About this site:</h3>
			<p>Content on this site is licensed under <a href="http://creativecommons.org/licenses/by/2.5/">CC By Attribution</a> unless otherwise specified. 
			Copyright (c) 2002-2006, <a href="http://al.tse.id.au/">Alastair Tse</a>.</p>
			<p>For more information, see <a href="http://al.tse.id.au/">al.tse.id.au</a>.</p>
			<p><script type="text/javascript" src="http://technorati.com/embed/itwctkzez.js"></script></p>
		</div>
		<div class="block">
			<h3>Is Made Possible By:</h3>
			<p>
			<dl>
				<dt><a href="http://ecto.kung-foo.tv/" class="clean">ecto</a>. </dt>
				<dd>Blogging client for Mac</dd>
				<dt><a href="http://djangoproject.com/" class="clean">Django</a>. </dt>
				<dd>Python Web Framework</dd>
				<dt><a href="http://www.lighttpd.net/" class="clean">lighttpd</a>. </dt> 
				<dd>Really Fast Web Server</dd>
				<dt><a href="http://www.saddi.com/software/flup/" class="clean">flup</a>. </dt>
				<dd>FastCGI for Python</dd>
			</dl>
			</p>
		</div>
        <div class="block">
            <h3>Search My Sites:</h3>
            <p>
           <div style='margin: 10px; text-align: center; width: 160px;'><form action='http://www.rollyo.com/search.html' ><fieldset style='margin: 0; padding: 4px 0 0 0; height: 60px; border: none; background: url(http://rollyo.com/remote/togo-bg4.png) no-repeat top left;'><div style="position: absolute; float:left; z-index:99; width: 46px; height: 50px;"><a href="http://rollyo.com"><img style="border: none;" height="50" width="46" src="http://rollyo.com/remote/x.gif"></a></div> <input type='text' size='30' style='float: left; width: 90px; margin: 2px 0 0 48px; padding: 0; font-size: 12px;' name='q' value='Search...' onclick='this.value="";' /><br /> <select name='sid' style='float: left; width: 78px; height: 15px; margin: 12px 0 0 46px; font-size: 7pt; padding: 0;'><option value='106081' selected='selected'>liquidx</option><option value='web'>Search The Web</option></select><input type='image' src='http://rollyo.com/remote/btn-togo.png' alt='Go' style='margin: 12px 0 0 3px; float: left;' /><input type='hidden' name='togo-v' value='1' /></fieldset></form></div>
               </p>
          </div>
         
    
		<div class="clear">&nbsp;</div>
        
    </div>



   <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
   <script type="text/javascript">
   _uacct = "UA-58117-1";
   urchinTracker();
   </script>

</body>
</html>
